The section describes the programming interface of the DMA Peripheral driver. More...

Data Structures
struct	dma_channel_t
	Data structure for the DMA channel management. More...

Typedefs
typedef void(*	dma_callback_t )(void *parameter, dma_channel_status_t status)
	A definition for the DMA channel callback function. More...

Enumerations
enum	dma_channel_status_t { kDmaIdle, kDmaNormal, kDmaError }
	Channel status for DMA channel. More...

enum	dma_transfer_type_t { kDmaPeripheralToMemory, kDmaMemoryToPeripheral, kDmaMemoryToMemory, kDmaPeripheralToPeripheral }
	Type for DMA transfer. More...

enum	dma_channel_type_t { kDmaInvalidChannel = 0xFFU, kDmaAnyChannel = 0xFEU }
	Type for the DMA channel, which is used for the DMA channel allocation. More...

DMA Driver
dma_status_t	dma_init (void)
	Initializes the DMA.

dma_status_t	dma_deinit (void)
	De-initializes the DMA.

dma_status_t	dma_register_callback (dma_channel_t chn, dma_callback_t callback, void para)
	Registers the callback function and a parameter. More...

uint32_t	dma_get_descriptor_status (dma_channel_t *chn)
	Gets the status of the EDMA channel descriptor chain. More...

uint32_t	dma_request_channel (uint32_t channel, dma_request_source_t source, dma_channel_t *chn)
	Requests a DMA channel. More...

dma_status_t	dma_free_channel (dma_channel_t *chn)
	Frees DMA channel hardware and software resource. More...

dma_status_t	dma_start_channel (dma_channel_t *chn)
	Starts a DMA channel. More...

dma_status_t	dma_stop_channel (dma_channel_t *chn)
	Stops a DMA channel. More...

dma_status_t	dma_config_transfer (dma_channel_t *chn, dma_transfer_type_t type, uint32_t size, uint32_t sourceAddr, uint32_t destAddr, uint32_t length)
	Configures a transfer for the DMA. More...

void	dma_IRQhandler (uint32_t channel)
	DMA IRQ handler for both an interrupt and an error. More...

DMA PERIPHERAL Driver

Overview

The DMA driver requests, configures, and uses the DMA hardware. It supports module initializations and DMA channel configurations.

Initialization

To initialize the DMA module, call the dma_init() function. Configuration data structure does not need to be passed. This function enables the DMA module and clock automatically.

Channel concept

DMA module consists of many channels. The DMA peripheral driver is designed based on the channel concept. All tasks should start by requesting a DMA channel and end by freeing a DMA channel. By getting a channel allocated, the user can configure and run operations on the DMA module. If a channel is not allocated, a system error may occur.

DMA request concept

DMA request triggers a DMA transfer. The DMA request table is available in chip configuration chapters in a Reference Manual.

Memory allocation

DMA peripheral driver does not allocate memory dynamically. The user must provide the allocated memory pointer for the driver and ensure that the memory is valid. Otherwise, a system error occurs. The user needs to provide the memory for the [dma_channel_t]. The driver must store the status data for every channel and the dma_channel_t is designed for this purpose.

Call diagram

To use the DMA driver, follow these steps:

Initialize the DMA module: dma_init().
Request a DMA channel: dma_request_channel().
Configure the TCD: dma_config_transfer().
Register callback function: dma_register_callback().
Start the DMA channel: dma_start_channel().
[OPTION] Stop the DMA channel: dma_stop_channel().
Free the DMA channel: dma_free_channel().

This is an example code to initialize and configure a memory-to-memory transfer:

uint32_t j, temp;
dma_channel_t chan_handler;
uint8_t *srcAddr, *destAddr;
fsl_rtos_status syncStatus;
srcAddr = malloc(kDmaTestBufferSize);
destAddr = malloc(kDmaTestBufferSize);
if (((uint32_t)srcAddr == 0x0U) & ((uint32_t)destAddr == 0x0U)) 
{
    printf("Fali to allocate memory for test! \r\n");
    goto error;
}
/* Init the memory buffer. */
for (j = 0; j < kDmaTestBufferSize; j++)
{
    srcAddr[j] = j;
    destAddr[j] = 0;
}
temp = dma_request_channel(channel, kDmaRequestMux0AlwaysOn62, &chan_handler);
if (temp != channel)
{
    printf("Failed to request channel %d !\r\n", channel);
    goto error;
}
dma_config_transfer(&chan_handler, kDmaMemoryToMemory,
                                0x1U,
                                (uint32_t)srcAddr, (uint32_t)destAddr,
                                kDmaTestBufferSize);
dma_register_callback(&chan_handler, test_callback, &chan_handler);
dma_start_channel(&chan_handler);
//Wait until channel complete...
dma_stop_channel(&chan_handler);
dma_free_channel(&chan_handler);

Data Structure Documentation

struct dma_channel_t

Data Fields
uint8_t	channel
	Channel number.

uint8_t	dmamuxModule
	Dmamux module index.

uint8_t	dmamuxChannel
	Dmamux module channel.

dma_callback_t	callback
	Callback function for this channel.

void *	parameter
	Parameter for the callback function.

volatile dma_channel_status_t	status
	Channel status.

Typedef Documentation

typedef void(* dma_callback_t)(void *parameter, dma_channel_status_t status)

A prototype for the callback function registered into the DMA driver.

Enumeration Type Documentation

enum dma_channel_status_t

A structure describing the status of the DMA channel. The user can get the status from the channel callback function.

Enumerator
kDmaIdle	DMA channel is idle.
kDmaNormal	DMA channel is occupied.
kDmaError	Error occurs in the DMA channel.

enum dma_transfer_type_t

Enumerator
kDmaPeripheralToMemory	Transfer from the peripheral to memory.
kDmaMemoryToPeripheral	Transfer from the memory to peripheral.
kDmaMemoryToMemory	Transfer from the memory to memory.
kDmaPeripheralToPeripheral	Transfer from the peripheral to peripheral.

enum dma_channel_type_t

Enumerator

kDmaInvalidChannel

Macros indicating the failure of the channel request.

kDmaAnyChannel

Macros used when requesting a channel.

kEdmaAnyChannel means a request of dynamic channel allocation.

Function Documentation

dma_status_t dma_register_callback	(	dma_channel_t *	chn,
		dma_callback_t	callback,
		void *	para
	)

The user registers the callback function and a parameter for a specified DMA channel. When the channel interrupt or a channel error happens, the callback and the parameter are called. The user parameter is also provided to give a channel status.

Parameters

chn	A handler for the DMA channel
callback	Callback function
para	A parameter for callback functions

uint32_t dma_get_descriptor_status ( dma_channel_t * chn )

Gets the left bytes to be transferred.

Parameters

chn	A handler for the DMA channel

uint32_t dma_request_channel	(	uint32_t	channel,
		dma_request_source_t	source,
		dma_channel_t *	chn
	)

This function provides two ways to allocate a DMA channel. The first way is a static allocation. The second way is a dynamic allocation. To allocate a channel dynamically, the user needs to set the channel parameter with the value of kDmaAnyChannel. The driver searches into all available free channels and assigns the first channel to the user. To allocate the channel statically, the user needs to set the channel parameter with the value of a specified channel. If the channel is available, the driver assigns the channel to the user. Notes: The user must provide a handler memory for the DMA channel. The driver initializes the handler and configures the handler memory.

Parameters

channel	A DMA channel number. If a channel is assigned with a valid channel number, the DMA driver tries to assign a specified channel to the user. If a channel is assigned with kDmaAnyChannel, the DMA driver searches all available channels and assigns the first channel to the user.
source	A DMA hardware request.
chan	Memory pointing to DMA channel. The user must ensure that the handler memory is valid and that it will not be released or changed by any other codes before the channel dma_free_channel() operation.

Returns: If the channel allocation is successful, the return value indicates the requested channel. If not, the driver returns a kDmaInvalidChannel value to indicate that the request operation has failed.

dma_status_t dma_free_channel ( dma_channel_t * chn )

This function frees the relevant software and hardware resources. Both the request and the free operations need to be called in a pair.

Parameters

chn	Memory pointing to DMA channel.

dma_status_t dma_start_channel ( dma_channel_t * chn )

Starts a DMA channel. The driver starts a DMA channel by enabling the DMA request. A software start bit is not used in the DMA Peripheral driver.

Parameters

chn	Memory pointing to the DMA channel.

dma_status_t dma_stop_channel ( dma_channel_t * chn )

Parameters

chn	Memory pointing to the DMA channel.

dma_status_t dma_config_transfer	(	dma_channel_t *	chn,
		dma_transfer_type_t	type,
		uint32_t	size,
		uint32_t	sourceAddr,
		uint32_t	destAddr,
		uint32_t	length
	)

Configures a transfer for the DMA.

Parameters

chn	Memory pointing to the DMA channel.
type	Transfer type.
size	Size to be transferred on each DMA write/read. Source/Dest share the same write/read size.
sourceAddr	Source address.
destAddr	Destination address.
length	Bytes to be transferred.

void dma_IRQhandler ( uint32_t channel )

Parameters

channel DMA channel number.

Data Structures

Typedefs

Enumerations

DMA Driver

DMA PERIPHERAL Driver

Overview

Initialization

Channel concept

DMA request concept

Memory allocation

Call diagram

Data Structure Documentation

Data Fields

Typedef Documentation

Enumeration Type Documentation

Function Documentation